home *** CD-ROM | disk | FTP | other *** search
/ Turnbull China Bikeride / Turnbull China Bikeride - Disc 2.iso / STUTTGART / EDITORS / ZAP130 / !Zap / Docs / ReadMe < prev    next >
Text File  |  1995-06-20  |  8KB  |  161 lines
  1. *************************************************************************
  2. * >ReadMe    Introduction to Zap documentation.            *
  3. *************************************************************************
  4.  
  5. This file is an 'index' to all the other documentation files in the Docs
  6. directory. All other documentation files begin with the prefix "E-".
  7.  
  8. This file is split into 3 sections:
  9.  
  10.     Section A:    How Zap works.
  11.     
  12.     Section B:    Writing extension modes.
  13.     
  14.     Section C:    Adding new commands to Zap.
  15.     
  16. Please read them in this order.
  17.  
  18. The following abbreviations/notations will be used in the documentation
  19. files:
  20.  
  21. '\E'    =    The entry conditions for this subroutine are ...
  22. '\X'    =    The exit conditions for this subroutine are ...
  23.  
  24. The following register conventions will be used:
  25.  
  26. R8    =    Window block pointer. (See E-Windows for defn)
  27. R9    =    File block pointer. (See E-File for defn)
  28. R10    =    Cursor block pointer. (See E-Cursors for defn)
  29. R11    =    Extension mode's workspace.
  30. R12    =    Zap module's workspace.
  31. R13    =    Full descending stack (1K), bottom = &8000
  32.  
  33. Thus for example if I write:
  34.  
  35. \E R8/R9
  36.  
  37. Then I mean that on entry, the subroutine has R8 pointing to the window
  38. block, and R9 pointing to a file block on some file (the file the call deals
  39. with). See also the files E-Zapcalls and E-Entry for the standard entry/exit
  40. conditions of most Zap calls.
  41.  
  42. Two BASIC programs are provided for you in the Docs directory. The first,
  43. E-Library defines all the Zap variable names you will need. The second,
  44. E-Template gives a template program for producing new modes/adding command
  45. tables. It creates a mode called 'Test' with mode number 15 based on text
  46. mode, and adds a command table with the command 'BEEPBEEP'.
  47.  
  48. *************************************************************************
  49. * Section A:    How Zap works.                        *
  50. *************************************************************************
  51.  
  52. When Zap starts up it initialises a 1K stack, claims fixed size buffers and
  53. initialises an operating system heap. File buffers are stacked on top of the
  54. heap and shifted about as the heap or other files changes size. Thus Zap's
  55. memory map can be summarised as:
  56.  
  57.         TOP    Wimpslot end
  58.             File n
  59.             ...
  60.             File 1
  61.             Heap
  62.             Fixed size buffers
  63.         &8000    Processor stack (R13) full descending.
  64.         
  65. To find out how to call Zap please see the file E-Zapcalls. All Zap calls
  66. will be described by their name beginning "Zap_". The calls Zap_Claim,
  67. Zap_Free, Zap_Ensure should be used to claim blocks from the heap. The call
  68. Zap_SplitBuffer should be used to change the buffer size of a file.
  69.  
  70. Each file has a corresponding file block giving information about that file.
  71. By convention R9 is used to hold a file block pointer. New file buffers can
  72. be created via Zap_CreateFile, Zap_CreateFileBlk, Zap_InstallFile and can be
  73. deleted via Zap_DeleteFile, Zap_DiscardFile. Files are stored in split buffer
  74. form. Please see E-File for details.
  75.  
  76. Similarly, each window has a corresponding information block. By convention a
  77. window block pointer is held in R8. Each window block determines uniquely a
  78. file block, giving the file showing in the window. Please see the file
  79. E-windows for details. New editing windows can be created by Zap_CreateFile,
  80. Zap_CreateWindBlk, Zap_InstallFile, Zap_NewView and can be deleted by
  81. Zap_DeleteWindow, Zap_DiscardWindow.
  82.  
  83. Cursor information blocks are described in the file E-Cursors. Cursor block
  84. pointers are conventionally held in R10. Zap's internal variables can be read
  85. by the call Zap_ReadVar and written by Zap_WriteVar. See the file E-Vars for
  86. details. By using this call you may read the block pointers of the standard
  87. cursor blocks.
  88.  
  89. Inserting/deleting/replacing data in files is accomplished via the calls
  90. Zap_Command and Zap_DoCommand. The former calls the extension mode to perform
  91. the required action and the latter is the low level call which performs the
  92. action directly. Thus in practice, Zap_Command calls the extension mode which
  93. then calls Zap_DoCommand. In this way the extension mode may alter the action
  94. of all inserts or deletes. For example, text mode uses this to accomplish
  95. wordwrap on all operations. See the file E-Zapcalls and E-Entry for more
  96. details.
  97.  
  98. Please use the Zap_StartOp/Zap_StopOp structure to concatenate insertions/
  99. deletions. This will give smooth update and will ensure that the operation is
  100. undone with only one press of the undo key.
  101.  
  102. *************************************************************************
  103. * Section B:    Writing extension modes.                *
  104. *************************************************************************    
  105.  
  106. Zap extension modes are numbered 0-255. Currently I have only reserved space
  107. for 32 of these (numbered 0-31). A mode consists of a table of entry points
  108. and flags. This should be held in a module so that the code is always 'mapped
  109. in to memory'. Default defined modes are listed below. 
  110.  
  111.     0    Text
  112.     1    Byte
  113.     2    Word
  114.     3    Ascii
  115.     4    Code
  116.     
  117. Before you start writing an extension mode, you should be familiar with
  118. writing modules (preferably in assembler). In most cases, you will simply
  119. wish to 'doctor' the input/output of one of the currently defined mode entry
  120. points. For example, you may wish to change the typed characters entry point
  121. of the TEXT mode to change `` to a left double quote. This is fairly simple
  122. to do. If, however, you wish to write a full blown mode with, for example,
  123. it's own display format, then you are strongly advised to contact me first.
  124. I will be able to give you more support than these text files, and will be
  125. able to add the new Zap calls and entry points that you may require.
  126.  
  127. To install a new mode you should write a module, which on initialisation
  128. calls Zap_AddMode with a pointer to the mode table. The location of this
  129. module should then be added to the external file so Zap will know where to
  130. load it from.  When Zap loads a module, it will examine the mode entry point
  131. table and copy it into its workspace, converting module offsets to actual
  132. addresses in the process. The call Zap_ReadMode can be used to find the
  133. address of both these tables for any given mode. Hence you can manually alter
  134. the mode entry point of any mode.
  135.  
  136. The entry point table format is described in the file E-Entry. Please note
  137. that you only have to fill in the first 8 words. In the fourth entry you
  138. specify a BASE MODE. This mode is called instead of yours for all the mode
  139. entry points you don't want to support/change. Hence in most cases you will
  140. set a base mode of 0 (ie TEXT), and set all of the entry points except those
  141. you wish to change to 0.
  142.  
  143. *************************************************************************
  144. * Section C:    Adding new tables of commands                *
  145. *************************************************************************
  146.  
  147. Zap currently has space reserved for up to 16 command tables, though I can
  148. easily increase this. The Zap and ZapBasic modules each use one, leaving 14
  149. for other uses. A command table consists of a pointer to a table of commands
  150. as described in the file E-Commands. The command table should be stored in a
  151. module and registered with Zap when the module initialises by calling the Zap
  152. entry point Zap_AddCommands. As with adding a mode, the module should be
  153. loaded by altering Zap's !Run file, so that the module is loaded after Zap,
  154. but before the Zap_Desktop command.
  155.  
  156. The main use of adding new commands is to add additional keymaps to Zap. For
  157. example, the extra commands needed by the EMACS keymap for Zap are store in
  158. the ZapBasic module.
  159.  
  160. See the file E-Command for fuller details.
  161.